home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / doors_1 / mpd204.zip / MSTPOPDL.DOC < prev    next >
Text File  |  1991-10-12  |  17KB  |  377 lines
  1.  
  2.                   MSTPOPDL - Most Popular Downloads
  3.  
  4.     MSTPOPDL (Most Popular Download) is a utility program for
  5.     Searchlight BBS programs. The program will only work with SL version
  6.     2.11 and higher.  A version is also available the works with v1.74
  7.     and higher, up to v1.77.
  8.  
  9.     MSTPOPDL (c) 1990,91 Jerry Carson, Fred Stoll, All rights reserved.
  10.  
  11.  
  12.  
  13.                          DISTRIBUTION NOTICE:
  14.  
  15.      You are encouraged to use, copy and distribute MSTPOPDL providing:
  16.  
  17.           No fee is charged for use, copying or distribution.
  18.  
  19.           It is not modified in any way.
  20.  
  21.     Files included in the MSTPOPDL package are:
  22.  
  23.           MSTPOPDL.EXE                   The program itself
  24.           MSTPOPDL.DOC                   This file
  25.           DEFAULT.TPL                    The default template file
  26.           COLOR.TPL                      The color template file
  27.           REGISTER.FRM                   Form to use when registering
  28.           BUG.FRM                        Form to use when reporting bugs
  29.  
  30.     If any of these files is missing or appears to have been tampered with
  31.     the latest version can be downloaded from the Wolverine BBS (see below).
  32.  
  33.     If you have any questions, you can contact the authors at:
  34.  
  35.     Send Mail to either, Jerry Carson or Fred Stoll on
  36.  
  37.     Wolverine BBS
  38.     (517) 631-3471
  39.     24 Hours
  40.  
  41.     Wolverine BBS is also an official Searchlight Support and Dealer
  42.     BBS. Wolverine's FIDO node is 1:159/1004. Wolverines supports
  43.     baud rates up to 9600 bps.
  44.  
  45.  
  46.  
  47.                            SETUP NOTICE:
  48.  
  49.     MSTPOPDL is very easy to use. Type "MSTPOPDL ?" at your prompt,
  50.     this will display the following help screen:
  51.  
  52. Invalid Parameter - ?
  53.  
  54. MSTPOPDL Version 2.04
  55.  
  56. Usage: MSTPOPDL [-nnn] [-d] [-e=ccc] [-f=path\filename.ext] [-i=path]
  57.                 [-l=name] [-l=@filename.ext] [-n] [-p] [-q] [-s]
  58.                 [-t=filename.ext] [-x=name] [-x=@filename.exe]
  59.  
  60. MSTPOPDL reads Searchlight .DIR files to determine the most often downloaded
  61. files and reports them.  The program's actions can be modified as follows:
  62.  
  63. [-nnn]                     Indicates the number of entries to report (max. 100)
  64. [-d]                       Generates a report for each .DIR file
  65. [-e=ccc]                   Create a separate report (dirname.ccc) for each .DIR
  66. [-f=path\filename.ext]     Routes the report to a file
  67. [-i=path]                  Indicates the path of CONFIG.SL2 file
  68. [-l=name]                  Only run on this directory name
  69. [-l=@filename.ext]         Only run on those directories listed, (max. 100)
  70. [-n]                       Do not generate a global report
  71. [-o=old]                   In case of ties, take oldest file
  72. [-o=new]                   In case of ties, take newest file
  73. [-p]                       Routes the report to the printer
  74. [-s]                       Reports the most download since last report
  75. [-t=fileame.ext]           Use filename.ext as template format
  76. [-q]                       No output to screen
  77. [-x=name]                  Do not include directory "name" in report
  78. [-x=@filename.ext]         Do not include directories in filename.ext in report
  79.  
  80.  
  81.                                 PARAMETERS
  82.  
  83. [-nnn]                 This parameter indicates the maximum number of files
  84.                        to report.  For example, -20 will report up to 20 of
  85.                        the most often downloaded files.  If there are less
  86.                        than 20, it will only report the actual number.  This
  87.                        number can range from 1 to 100 and the default is 10.
  88.  
  89. [-d]                   This will generate a report for each .DIR listed in
  90.                        your .DEF file.  This action can be modified by the
  91.                        -l and -x options.
  92.  
  93. [e=ccc]                This parameter causes the reports to be split into
  94.                        separate files for individual use.  These files have
  95.                        the name of the .DIR with the extension .ccc.
  96.                        Example: The report for UPLOADS.DIR with -e=txt will
  97.                                 be placed in UPLOADS.TXT.
  98.                        The overall report is placed in a file called: GLOBAL.ccc
  99.  
  100. [-f=filename.ext]      The report is routed to the file specified.  If an existing
  101.                        is specified it will be overwritten.
  102.  
  103. [i=path]               This option can be used to indicate the path that
  104.                        CONFIG.BBS resides in.  This is useful when MSTPOPDL
  105.                        does not reside in the searchlight program directory.
  106.  
  107. [-l=name]              This option causes only the area named (and all areas
  108.                        named after) to be included in the reports.  This is
  109.                        useful for getting reports on individual areas.
  110.  
  111. [-l=@filename.ext]     This option specifies a file of areas to be included
  112.                        in the report.  This is an ASCII file with the area
  113.                        name being the first thing on the line and one area
  114.                        per line.  The default extension for this file is LST.
  115.  
  116. [-n]                   This option indicates that the generation of the
  117.                        global or overall report is to be suppressed.
  118.  
  119. [-o=old]               If two files have been downloaded the same number of
  120.                        times, the oldest file is placed and the list and
  121.                        the newer file is forgotten.  This is the default.
  122.  
  123. [-o=new]               If two files have been downloaded the same number of
  124.                        times, the newest file is placed and the list and
  125.                        the older file is forgotten.
  126.  
  127. [-p]                   The report is routed to the LST device.  Care should
  128.                        be taken to insure that the printer is online and has
  129.                        sufficient paper before using this option.
  130.  
  131. [-q]                   Causes the program to be run in 'quite' mode.  No
  132.                        output is generated to the screen.
  133.  
  134. [-s]                   Instead of using the total number of times a file has
  135.                        been downloaded, this option bases the report on the
  136.                        number of times the file has been downloaded since the
  137.                        last -s option was used.  When used this option will
  138.                        cause a .MPD file to be created for each .DIR file
  139.                        scanned.  These files contain a snapshot of the .DIR
  140.                        files for use in later runs.  The first time this
  141.                        option is used the report will be based on the total
  142.                        downloads but the .MPD files will be created.
  143.  
  144. [-t=filename.ext]      Indicates the name of the template file to use.  Two
  145.                        templates are provided; DEFAULT.TPL and COLOR.TPL.
  146.                        More can be written by the user for his or her
  147.                        personal preference.  See the 'TEMPLATES' section for
  148.                        information on creating template files.  The default
  149.                        extension is .TPL.
  150.  
  151. [-x=name]              The area named is NOT included in the reports
  152.                        generated.  More areas can be named with additional
  153.                        -x options.
  154.  
  155. [-x=@filename.ext]     The areas listed in filename.ext are excluded from
  156.                        the reports generation.  The format of this file is
  157.                        the same as for the -l option.  This way the same file
  158.                        can be used to generate a report based on a list of
  159.                        files then be used to exclude those files from another
  160.                        report.  The default extension is .LST.
  161.  
  162.  
  163.  
  164.                                  EXAMPLES
  165.  
  166. You can configure MSTPOPDL almost anyway you like. You can have it
  167. just list a global listing of your most popular downloaded files or
  168. send it to text file, you can also have a different text file for each
  169. file area that will be displayed upon entry to that particular file area.
  170.  
  171. MSTPOPDL -100
  172. -- Displays the top 100 all time downloaded files
  173.  
  174. MSTPOPDL -F=D:\FILES\TEXT\MSTPOPDL.TXT
  175. -- Routes the report to a ascii text file called MSTPOPDL.TXT
  176.  
  177. MSTPOPDL -F=D:\FILES\TEXT\MSTPOPDL.TXT -T=COLOR
  178. -- Routes the report to a ascii text file called mstpopdl.txt that
  179.    has Searchlight color codes.
  180.  
  181. MSTPOPDL -D -F=D:\FILES\TEXT\MSTPOPDL.TXT
  182. -- Creates reports for each .DIR file and routes to report to an ASCII
  183.    text file called MSTPOPDL.TXT
  184.  
  185. MSTPOPDL -E=TXT -F=D:\FILES\TEXT\MSTPOPDL.TXT -T=COLOR
  186. -- Creates individual color report files for each filename.DIR with the
  187.    name filename.TXT in the default directory.  It places the global
  188.    report in a file called MSTPOPDL.TXT
  189.  
  190. MSTPOPDL -L=USER -N
  191. -- Reports on USER.DIR only.
  192.  
  193. MSTPOPDL -L=@DIRS.LST -P
  194. -- Creates reports for each of the names listed in DIRS.LST (one name per
  195.    line ASCII only) and prints it.
  196.  
  197. MSTPOPDL -E=TXT -S -F=D:\FILES\TEXT\MSTPOPDL.TXT -T=COLOR
  198. -- Reports the most frequently downloaded files since the last time
  199.    MSTPOPDL was run with the -S option.  If it is the first time it
  200.    will generate an overall report.  This options takes some time and
  201.    generates a .DLS file for each .DIR file it processes.
  202.  
  203.  
  204.  
  205.                               TEMPLATES
  206.  
  207.    The template file is an ASCII file and can be created using any editor
  208.    that will generate simple ASCII text.  Each line consists of two fields
  209.    separated by a comma.  The first field is the placement indicator which
  210.    consists of a single character and must be first on the line.
  211.    Valid values for this field are:
  212.  
  213.                        1      Header
  214.                        2      Sub-header
  215.                        3      File line
  216.                        4      Sub-trailer
  217.                        5      Trailer
  218.                        ;      Comments
  219.  
  220.     The lines in each section (except 3 and ;) are placed in the order that
  221.     they appear in the template file.  If more than one type 3 lines exist
  222.     they are rotated starting with the first line of type 3.  For example,
  223.     if there are 2 lines of type 3 in the template file the first file will
  224.     use the first line, the second will use the second, the third will use
  225.     the first, etc.
  226.  
  227.     The line with a placement indicator of ; are comments and will not be
  228.     placed in the output stream.  Types 1 and 5 appear once per output
  229.     stream or file while types 2 and 4 are repeated for each area.
  230.  
  231.     An example of a valid template file is:
  232.  
  233.     1,
  234.     1,MSTPOPDL -  Ver. %vr, (C) 1990,91 Jerry Carson, Fred Stoll
  235.     1,
  236.     2,
  237.     2,\CE80Top %no Downloads for %bn (%dn) as of %dt
  238.     2,
  239.     2,No.  Filename     Size D/Ls  Date      Description
  240.     2,--------------------------------------------------------------------
  241.     3,%rk:r03 %fn:l08 %fx:l03 %sk:r04K %dl:r03 %fd:r08 %ds
  242.  
  243.  
  244.     This may seem confusing at first, but once you start working with it is
  245.     really quite flexible.
  246.  
  247.     The second field is the line format.  These consist of normal text,
  248.     variable fields, and format codes.  Variable fields are two letter codes
  249.     preceded by a % sign.  This field is replaced by data at run-time.
  250.     Optionally these variables can be followed by a :xnn where x is either
  251.     'R' or 'L' to indicate whether the field is the right or left justified,
  252.     and nn is the 2 digit length of the field.  The variable fields are
  253.     listed below.
  254.  
  255.     Variables can be divided into two groups, GLOBAL and LOCAL.  GLOBAL
  256.     variables are can be used anywhere, while LOCAL variables can only be
  257.     used in line of type 3.
  258.  
  259.  
  260.     Global variables:
  261.  
  262.        %bn         BBS name as found in the CONFIG.BBS
  263.        %dd         Directory description.  This is the description of the
  264.                    current file area. This variable should not be used in
  265.                    type 1 lines.
  266.        %dn         Directory name.  This is the file name of the .DIR file
  267.                    and should not be used in type 1 lines.
  268.        %dt         Current date as defined by the system clock
  269.        %ld         Date of last run of MSTPOPDL using -s option.  Only valid
  270.                    if the -s options is used.
  271.        %lf         Total number of files in this area, should not be used in
  272.                    type 1 lines.
  273.        %ls         Total space used by files in this area.  Should not be
  274.                    used in type 1 lines.
  275.        %no         Number of files to report, ie. top 10
  276.        %nm         Actual number of files reported in this area.
  277.        %tf         Total number of files.
  278.        %ts         Total space used by files.
  279.        %vr         MSTPOPDL version number
  280.  
  281.     Local variables:
  282.  
  283.        %dl         Number of times downloaded; this is either total or since last
  284.                    time depending on the -s option.
  285.        %ds         Description of the current file
  286.        %d1         Line 1 of extended description
  287.        %d2         Line 2 of extended description
  288.        %fd         Creation date of the current file
  289.        %fn         Name of current file
  290.        %fx         Extension of current file
  291.        %rk         Ranking in list.  The first file is 1, second is 2, etc.
  292.        %sk         Size of the file in K.  Includes 1 decimal place.
  293.        %sb         Size of the file in bytes
  294.  
  295.     The format codes are used control the placement or content of a line.
  296.     Each one consists of a \ followed by a two letter code followed by a 2
  297.     digit data field.
  298.  
  299.     Format codes:
  300.  
  301.        \CEnn       Center remaining text in a field of nn positions.
  302.  
  303.        \HXhh       Replace with the ASCII character whose hex value is hh.
  304.                    This can useful for inserting your own ANSI or printer
  305.                    control codes.
  306.  
  307.        \TBnn       Tab to position nn on line.  Note you may not tab
  308.                    backwards.
  309.  
  310.        \??         Insert random color code.  This will be a random color
  311.                    other than black.
  312.  
  313.  
  314.                           SHAREWARE NOTICE:
  315.  
  316.    MSTPOPDL is shareware. You can use it for 30 days. After 30 days
  317.    you either have to register or stop using it.
  318.  
  319.  
  320.  
  321.                           DISCLAIMER NOTICE:
  322.  
  323.  
  324.                          D I S C L A I M E R
  325.  
  326.     The authors hereby disclaims all warranties relating to this
  327.     software, whether express or implied, including without
  328.     limitation any implied warranties of merchantability or fitness
  329.     for a particular purpose.  The authors will not be liable for any
  330.     special, incidental, consequential, indirect or similar damages
  331.     due to loss of data or any other reason.
  332.  
  333.     The person using the software bears all risk as to the quality
  334.     and performance of the software.
  335.  
  336.     MSTPOPDL has not been tested for door use. However, it should work as a
  337.     door program, keep in mind that MSTPOPDL has no modem support.
  338.  
  339.     MSTPOPDL is designed to be run in your event.def or event.bat file.
  340.     an example.bat file is enclosed with MSTPOPDL.ZIP file.  Bug reports
  341.     should be made on Wolverine BBS (517-631-3471) to either Jerry Carson
  342.     or Fred Stoll.  We feel that MSTPOPDL is a solid program, but sometimes
  343.     bugs do creep in.  The first person to report a particular bug will
  344.     receive free registration.  This offer is given solely at the authors
  345.     discretion and may be retracted at any time.  To report a bug please
  346.     fill out and return the BUG.FRM file with the requested information.
  347.  
  348.  
  349.  
  350.                                HISTORY:
  351.  
  352.    MSTPOPDL v1.00 - First Public Release
  353.    (October 1990)
  354.  
  355.    MSTPOPDL v1.01 - Fixed problem reading some .DEF files
  356.    (November 1990)
  357.  
  358.    MSTPOPDL v1.02 - Fixed problem with using -e and -f option together
  359.    (December 1990)  Added the -q and -x options
  360.                     Added the ability to read .TPL files
  361.                     Removed -b,-cs, and -cf options as no longer needed
  362.  
  363.    MSTPOPDL v2.00 - First Public Release for SL 2.0 and greater.
  364.    (April 1991)
  365.  
  366.    MSTPOPDL v2.01 - Minor bug fixes.
  367.    (June 1991)
  368.  
  369.    MSTPOPDL v2.02 - Fixed problem with missing FILEDEF.
  370.    (June 1991)
  371.  
  372.    MSTPOPDL v2.03 - Fixed problem with length being shown incorrectly.
  373.    (July 1991)
  374.  
  375.    MSTPOPDL v2.04 - Added -o option
  376.    (October 1991)
  377.